home *** CD-ROM | disk | FTP | other *** search
/ Software of the Month Club 1998 March / Software of the Month Club 1998 March.iso / mac / Business / PowerReplace 6.3 / Plugin / PowerReplace User’s Guide / PowerReplace User’s Guide.rsrc / TEXT_132_4 - Tutorial.txt < prev    next >
Text File  |  1997-12-21  |  10KB  |  268 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6. General Infomation
  7. PowerReplace converts text files using filter.
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23. To realize the conversion, you need to write your own filter. There is some filter ΓÇ£ready to useΓÇ¥ in the Filter folder. Please see the index in the Filter folder. You may also get more filter from my home page.
  24.  
  25. Creating a New Filter
  26. In this tutorial, we will create a simple filter. By using it, PowerReplace will swap the two strings "read" and "write" in text file.  For complete reference about filter, please see Chapter 5: Filter Syntax Reference.
  27.  
  28. (1) Launch PowerReplace application.
  29. (2) Write the following lines in the window ΓÇ£UntitledΓÇ¥:
  30.   % Comments: this filter swaps "read" and "write"
  31.   % make sur there is no "re@d" in your text file.
  32.   "read"       "re@d"     % save   "read"  to "re@d"
  33.   "write"      "read"     % change "write" to "read"
  34.   "re@d"       "write"    % change "re@d"  to "write"
  35.  
  36.  
  37.  
  38. Γùè If you have a very long line to edit, the line editor can help you. Please see the section Using Line Editor to Edit Long Line later in this Chapter.
  39.  
  40. Γùè It is possible that there is some initial text in the window "Untitled". It contains help message for the beginners. The initial text  in the three windows are stocked in the "Plugin:Initial Text ForΓǪ" folder. You can change them or delete them if you wish.
  41.  
  42. Γùè To open and edit an existed filter, or import an existed text file as filter, select Open FilterΓǪ (or press ΓîÿO) from the File menu. 
  43.  
  44. Γùè You can set some option for the editor, please see the section Text Option later in this Chapter.
  45.  
  46. Converting a Text File
  47. In the ΓÇ£UntitledΓÇ¥ window, click the Convert File button, then locate and select MyText to be converted from the standard get file dialog box. ThatΓÇÖs all. Normally a new file named ΓÇ£MyText.outΓÇ¥ has been created in the same folder as the file ΓÇ£MyTextΓÇ¥. 
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68. Γùè You can use Balloon Help system to get description for buttons and menu items. Select Show Balloons from the help menu.
  69.  
  70. Γùè It is possible that the filter has some errors. To debug filter, see Debugging Filter: Syntax Error and Logical Error later in this chapter. For complete reference about filter, please see Chapter 5: Filter Syntax Reference.
  71.  
  72. Γùè You can set some options. For example, you may want to set the output fileΓÇÖs name by adding ΓÇ£.newΓÇ¥ to the input fileΓÇÖs name, that is ΓÇ£MyText.newΓÇ¥. For complete description about how to set option, please see Filter Information later in this chapter.
  73.  
  74. Converting the Clipboard
  75. To realize the conversion in a text editor (like BBEdit, Word), without saving the text as text file (of type 'TEXT'),  follow these steps:
  76. (1) Under the text editor, select all your text by ΓîÿA, copy the selection by ΓîÿC. Now your text is in the clipboard. 
  77. (2) Under PowerReplace, in the ΓÇ£UntitledΓÇ¥ window, click the Convert Clipboard button.
  78. (3) Return to the text editor, paste the clipboard to your text by ΓîÿV.
  79.  
  80. Converting Text Files Using Drag/Drop
  81. To realize frequently  this conversion using drag/drop, follow these steps:
  82. (1) Save your filter. From the File menu, select Save or Save AsΓǪ  Then give this filter file a name, for example, ΓÇ£SimpleFilterΓÇ¥ in the put file dialog box. Put it into the Filter folder.
  83. (2) Quit and relaunch PowerReplace application for some update information. 
  84. (3) After confirming that there is an item SimpleFilter  in the Filter menu, select it. Then quit. PowerReplace saves the selected filter SimpleFilter  in its preference file.
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97. (4) Under Finder, select your text files, drag and drop them onto the PowerReplace icon.
  98. ThatΓÇÖs all. Normally the new files named ΓÇ£xxxxx.outΓÇ¥ have been created in the same folder as the files ΓÇ£xxxxxΓÇ¥.
  99.  
  100. Γùè To realize the same conversion that you have done the last time, you need only drag/drop your files onto the PowerReplaceΓÇÖs icon under Finder, because the selected filter is rememberred in the preference.
  101.  
  102. Γùè Shortcuts. To select a filter and avoid opening it:  Γîÿ +  Select Filter.
  103.  
  104. Γùè The name of the selected filter appears in the toolbar.
  105.  
  106. Converting All Text Files in a Folder Using Drag/Drop
  107. If you drop folder onto the application icon, PowerReplace converts all files in this folder and in the sub-folders of this folder by recurrence.
  108.  
  109. Converting Text Files Using SelfReplace
  110. Please see Chapter 6: About SelfReplace.
  111.  
  112. Converting Text Files Using Script
  113. If you have AppleScript system, you can write a small script for your conversion. Using the scripts, you have the following advantages:
  114.  - Script is a very small file.
  115.  - The filter need not be in the Filter folder.
  116.  - Text file can be converted by filter1, then filter2. (Pipe)
  117. The following is the PowerReplace apple eventsΓÇÖs dictionary:
  118.  
  119. use filter: set new filter file
  120.     use filter  string  -- name of the filter file to be used.
  121.  
  122. current filter: get the name of the current filter file
  123.     current filter
  124.     Result:   string  -- name of the current filter file.
  125.  
  126. convert: convert text file
  127.     convert  alias  -- the input text files.
  128.         using  alias  -- the filter file to be used.
  129.         [message  boolean]  -- show the success message after conversion?
  130.     Result:   alias  -- the output files.
  131.  
  132. convert clipboard: convert clipboard
  133.     convert clipboard
  134.         using  alias  -- the filter file to be used.
  135.         [message  boolean]  -- show the success message after conversion?
  136.  
  137. The following is an example:
  138.  
  139. on open doc
  140.      set myfilter to choose file with prompt "Where is the filter?"
  141.          
  142.     tell application "PowerReplace 6.1 68K"
  143.         launch
  144.         activate
  145.         set output to convert doc using myfilter with message
  146.         quit
  147.     end tell
  148. end open
  149.  
  150. You can find more examples in the Example Script folder.
  151.  
  152. Filter Information
  153. In the filter window, click Information, the filter information dialog box will display. You can set filter option in this dialog box. For complete description about each dialog item, please use Balloon Help system.
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175. ΓÇó Simple Output File Name. The formula for the output file name is:
  176.     output file name = input name - deleteSuffix + addSuffix.
  177. For example, if input file name is "index.html", deleteSuffix is ".html", and addSuffix is ".tex". Then the output file name will be "index.tex". If the deleteSuffix can not be found, at the end of the input file name, then ignore the deleteSuffix.
  178. Change deleteSuffix and addSuffix in the "Information Window" of the filter.
  179.  
  180. ΓÇó Specify input file. You can specify input files. 4 cases:
  181. - all type, 
  182. - all text file of type 'TEXT', 
  183. - the name suffix is the string ".html",
  184. - the name suffix is NOT the string ".gif".
  185. You can change ".html" and ".gif" by other strings. Change this option in the  "Information Window" of the filter.
  186.  
  187. Debugging Filter: Syntax Error
  188. It is possible that the filter has some syntax errors. For complete reference about filter, please see Chapter 5: Filter Syntax Reference. Suppose that you write the following line 
  189.   "re@d"       3write"    % change "re@d" to "write"
  190. in place of the last line of SimpleFilter. Click Convert File, Convert Clipboard or Check Syntax, the message window will display in the front. You can find enough help for correct the error.
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210. Debugging Filter: Logical Error
  211. Of course, PowerReplace can not detect the logical errors. When the logical error occur, you need to do the following frequently:  
  212.  
  213.                     Edit filter -> Convert -> Check input and output
  214.  
  215. In this case, you can put the input text in the ΓÇ£InputΓÇ¥ window. Click Convert In->Out. PowerReplace does the convertion, and then displays the output text in the ΓÇ£OutputΓÇ¥ window.
  216.  
  217. Γùè You can edit the text in the ΓÇ£InputΓÇ¥ window, but can not edit the text in the ΓÇ£OutputΓÇ¥ window.
  218.  
  219. Γùè The initial text  in the three windows are stocked in the "Plugin:Initial Text ForΓǪ" folder. It gives help for the beginners. You can change them or delete them if you wish.
  220.  
  221.  
  222. Text Option
  223. Select Text Option from the Edit menu. You can change text font and text size in the filter window. For the Automatical Alignment option, please see the following examples. If the filter text is
  224. %123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
  225. "ab"   "CD"
  226. "xy"                "XY"
  227. "xyxyxyxyxyxyxyxyx" "XY"
  228.  
  229. Then after check syntax, it will be:
  230. 1. without Automatical Alignment option.  The text is not changed.
  231.  
  232. 2. with Automatical Alignment option, Tabulation=16, Condense.
  233. %123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
  234. "ab"            "CD"
  235. "xy"            "XY"
  236. "xyxyxyxyxyxyxyxyx"             "XY"
  237.  
  238. 3. with Automatical Alignment option, Tabulation=16, Extend.
  239. %123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
  240. "ab"            "CD"
  241. "xy"                            "XY"
  242. "xyxyxyxyxyxyxyxyx"             "XY"
  243.  
  244.  
  245.  
  246. Using Line Editor to Edit Long Line
  247. A good line in the filter window is like the following:
  248.              first-stuff     second-stuff    the-rest
  249. If you have a long line in the filter window to edit, keep the cursor in that line and select "Line Editor"  from the Edit menu. The Line Editor window displays. In this window, the first stuff, second stuff and the rest of that long line will be  separated in three text fields. You can edit them more easily. 
  250.  
  251. Γùè  We know that, in the first and second stuffs, \" represents ". In the line editor, we do NOT use this representation because there is no confusion. When back to the filter window by clicking the OK button, the line editor will replace " by \" automatically before making the long line.
  252.  
  253. Γùè  In the line editor, you can type CR or LF. When back to the filter window by clicking the OK button, the line editor will remove all CR and LF before making the long line.
  254.  
  255. Γùè  If the selected line is not a "good line", i.e., has no first stuff, or second stuff, then the line editor window does not display.
  256.  
  257.  
  258. Organizing the Filter Menu
  259. If there is too many filter files, the Filter menu will contain too many items. PowerReplace provides two ways to organize the Filter menu:
  260.  
  261. Γùè you can mask someone of them by labelling (coloring) under Finder. PowerReplace scans only the folder and filter file without label(color).
  262.  
  263. Γùè A filter named "(-" (without quotation marks) makes a divider line in the Filter menu.
  264.  
  265. Stack Windows
  266. Use Stack Windows command in the Control menu to move all windows to its standard position.
  267.  
  268.